Summary

Closes #1222.

Adds an opt-in themeConfig.api.schemaExpansion option that controls the default expansion depth of nested request/response schema trees, plus an inline icon control next to each schema header that lets readers change the depth at view time. The selected depth is persisted in localStorage.

Inspired by Redoc's schemaExpansionLevel — useful primarily for envelope-wrapped APIs (e.g. { status, meta, data: {...} }) where readers otherwise have to manually click into every data property.

How it works

• New SchemaExpansionProvider and SchemaDepthProvider contexts thread the active expansion level and per-node depth without prop-drilling through the recursive Schema renderer.
• SchemaNodeDetails opens its <Details> when depth < level. Keying on level forces a remount on level change so the control feels responsive without losing per-row click toggling afterward.
• New SchemaExpansionControl renders a small icon trigger inline with the Body / Schema headers; clicking opens a compact popover with depth options including "All". The popover is positioned with position: fixed (computed from the trigger's bounding rect) so it isn't clipped when the surrounding <details> is collapsed, and closes on scroll to stay visually anchored.
• Behavior is unchanged when schemaExpansion is unset — no control rendered, schemas remain collapsed by default.

Config

themeConfig: {
  api: {
    schemaExpansion: {
      enabled: true,         // show the depth control (default: false)
      default: 1,            // initial depth — "all" supported (default: 0)
      max: 4,                // max depth offered by the control (default: 4)
      persist: true,         // remember last choice in localStorage (default: true)
    },
  },
}

Accessibility & i18n

• <button> trigger with aria-haspopup="menu", aria-expanded, aria-controls, aria-label, and a native title tooltip.
• Popover has role="menu" and its own aria-label; options are role="menuitemradio" with aria-checked and a translated per-option label ("Expand to depth N").
• Focus moves to the active option on open; ← / → cycle through options; ESC closes and returns focus to the trigger.
• All user-facing strings are routed through @docusaurus/Translate and registered in translationIds.ts under OPENAPI_SCHEMA_EXPANSION (theme.openapi.schema.expansion.*).

Files

• packages/docusaurus-theme-openapi-docs/src/theme/SchemaExpansion/ — new context module, control component, BEM-style SCSS
• packages/docusaurus-theme-openapi-docs/src/theme/Schema/index.tsx — SchemaNodeDetails reads context, threads depth
• packages/docusaurus-theme-openapi-docs/src/theme/{Request,Response}Schema/index.tsx — render the inline control
• packages/docusaurus-theme-openapi-docs/src/theme/ApiItem/index.tsx — wraps the page in the provider
• packages/docusaurus-theme-openapi-docs/src/theme/translationIds.ts — registers the new translation keys
• packages/docusaurus-theme-openapi-docs/src/types.d.ts — types schemaExpansion on ThemeConfig.api
• demo/examples/tests/schemaExpansion.yaml — envelope-wrapped fixture for manual exercise
• demo/docusaurus.config.ts — enables the option in the demo

Test plan

• Visit /docs/tests/get-user-envelope-wrapped — the depth icon appears to the right of the "SCHEMA" header
• With default: 1, the top-level data property is open on load; deeper children are not
• Clicking the icon opens a popover with 0 1 2 3 4 All; selecting a value adjusts the open depth across the tree
• Selection persists across reloads (localStorage key docusaurus-openapi-schema-expansion-level)
• Same control appears next to the "BODY" header on the create-user endpoint
• Tab/arrow-key navigation works inside the popover; ESC closes and returns focus to the trigger
• Removing schemaExpansion from the demo config hides the control and restores prior collapsed-by-default behavior
• Mobile / narrow viewport: popover stays anchored to the trigger and doesn't overflow

🤖 Generated with Claude Code